feat: surface gamma_flip_status and handle null gamma_flip - #2
Merged
Conversation
The API (endpoint version 2026.09.09) made gamma_flip nullable and added a sibling gamma_flip_status string that reads "available" when a level is published and otherwise carries a reason code (no_boundary, stored_sign_mismatch, insufficient_local_coverage, insufficient_quote_quality, sensitive_root, uncertain_root_path, search_budget, quality_budget). Roughly two in three chains now return a null flip, with regime falling back to "unknown". This adds gamma_flip_status alongside every gamma_flip declaration in the response types and fixes the quickstart example, which formatted the level with :.2f and therefore raised TypeError on NoneType.__format__ for the now-common null case; it prints the reason code instead. The README quick start is updated to match, since it is rendered on PyPI. Clients should treat any status other than "available", including codes added later, as no level published. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The three flow endpoints (/v1/flow/levels, /v1/flow/gex, /v1/flow/live) pair their value field live_gamma_flip with a status field named plainly gamma_flip_status, not live_gamma_flip_status, so searching only for the gamma_flip identifier missed them and FlowLevelsResponse, FlowGexResponse and FlowLiveResponse were dropping a field the API actually returns. This adds the declaration to all three, noting the asymmetric wire name at each site, which brings the package to fourteen gamma_flip_status declarations. It also brings the reference docs in line: docs/api.md gains the field in thirteen JSON examples, five response-field tables and three notable-metrics lists, marks gamma_flip nullable where it was not already, and carries a callout explaining the reason codes and the flow naming asymmetry; AGENTS.md gains an entry in its silent-null traps list warning that formatting gamma_flip as a number raises TypeError; llms.txt gains a nullability note beside its typed-response example. article-flashalpha-python-sdk.md is left alone as marketing prose rather than a field reference, and its snippets do not format the level numerically. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the
gamma_flip_statusfield to every response model that carries a gamma flip, and fixes null-handling bugs the change exposes.Why
The FlashAlpha API (endpoint version
2026.09.09, deployed 2026-09-09) now publishesgamma_fliponly when the option book supports it. Roughly two chains in three returngamma_flip: nullwithregime: "unknown". A new sibling fieldgamma_flip_statussays why:available, or a reason code such assensitive_root,insufficient_quote_quality,insufficient_local_coverage,no_boundary,stored_sign_mismatch,uncertain_root_path,search_budget,quality_budget.Statically-typed SDKs bind only declared members, so before this change the field was silently dropped and callers had no way to learn why a level was withheld.
Field naming
The API uses two value-field names but only one status name:
gamma_flipgamma_flip_statuslive_gamma_flipgamma_flip_statusNote the asymmetry: the status is not named
live_gamma_flip_status. This was verified by sweeping 23 production endpoints for every key containinggamma_flip; exactly three names exist.Typed as a plain nullable string, never an enum, so a future reason code cannot break deserialization. Callers should treat any unrecognised value as unavailable.
Verification
Every value field in this repo is paired 1:1 with a status field, checked by counting serializer-bound declarations only. Build and tests are green.
Not included
No version bump and no registry publish. Existing integration tests that assert a non-null flip are left untouched; they encode the old contract and need a separate decision.
🤖 Generated with Claude Code